All modify commands are replied to with either 'ok' or error. If more than one gadget parameter is changed by the modify command the reply can be 'ok ok ...' . A reply of a blank line means the modify command was not understood and was ignored.
See the documentation for each gadget type for information on modifying that type of gadget type.
Modify commands that change gadget parameters begin with 'id GID' Gadgets are modified with the following line format
The parameters allowed depend on the type of gadget that GID refers to.
NOTE: When modifying gadgets on a clicktab page, you should add the page parameter to the modify line.
Modify Parameters for all gadgets
(except menu, arexxhost, textattr)
------------------------------
address
Read the address of object asociated with the GID and information about the gadget type. This modify command MUST be ' id GID address' and returns 'ADDRESS GADGETTYPE'
An address of 0 means no object is asociated with the GID.
page="GID"
Specify the clicktab gadget that controls the page containing the gadget to be modified. Most gadgets seem to modify fine without this being set, but it must be used for string gadgets. It should probably be used for all gadgets on clicktab pages to ensure future compatability.
NOTE: you supply the Gadget ID of the clicktab, NOT the number of the page inside the clicktab.
set
'Set' sets gadget parameters from the supplied tag list. Both 'set' and 'tags' must be used to do this.
tags="tags|data[|tag|data...]|0
A list of tag and value pairs in HEX. Do not forget the trailing null !
Get="hexvalue"
This special modify command lets you read a value associated with a gadget The pipe replies with 'ok value' when successful, a blank line if it fails.
example 'id 3 get xxxxxxxx'
This reads the selected color in a palette gadget (whose GID is 3).
Read Gadget modify instruction
------------------------------
'id GID read'
Read must not be used with other parameters besides GID.
'id GID read'
Read the gadget specified by GID. The pipe returns the same information as when a user hits a gadget but without the leading 'gadget gid'. In the case of GID=0 read returns the windows 'left top width height' settings.
Gadget interconnection modify
-----------------------------
This function may only be useful to programmers already familiar with interconnection who have registered CA documentation.
Target="gadget_ID" (tar=)
The gadget to be interconnected with.
tags="tagsource|tagdest[|tagsource|tagdest..]|0
The list of tags for interconnection in HEX. Tags must be in pairs, and do not forget the trailing null!
Pointer data is the definition for a pointer. For more information see the intuition call SetPointer(). Pointerdata="" is a special case setting the pointer to a null (invisable) pointer.
specialchar="character" (sc=)
'Character' is a single character that replaces '|', in use as a seperator inside parameters like chooserlabels, tags, penmapdata, ...
Quiet (q)
Tell the pipe not to reply to the modify commands. This is actually a toggle switch turning replies off and on. SOME modify commands are ALWAYS replied to. (addnode and getfile
selected 0|1)
refresh (ref)
Refresh the gadget referenced by GID. The refresh command can be combined with any other modify command and is always executed last. GID=0 will refresh the windows root layout, this is the best way to refresh all gadgets.
Refresh without a GID specified will refresh the entire window, usually it is better to refresh the root class as described above.
close
Close the CA window. Dispose of window and end CApipe.
tick=number
End the modify conversation, Reply with a tick event after number/100 seconds.
Continue (con)
End the modify conversation.
Modifyoff (m)
End the modify conversation AND turn modify off. (do not start any new modify conversations). Note there will be no way to turn modify back on.
Bubble Help
------------
Each GUI can show one buble help window at a time.
bubble top=numx left=numy gt="Help Text"
This opens a bubble showing the help text. Top and left are mouse location for the help (as sent to you in the help event you are responding to). Any previous help window will be closed.
'bubble' sent with no parameters will close the bubble with out opening a new one.
Image Functions
----------------
FreeImage="num" fi=
if num=-1 Dispose of a previously defined image without using it. Else free the root bitmap image in buffer num. Be careful not to do this while images still exist that reference this root bitmap.
Draw="num" top="num" left="num"
Draw an image into the gui. Num is the number of the predefined image to be
drawn. You MUST set 'top' and 'left' and can also set
nozz
Top and left are relative th the whole window rather than the inner panel.
noclip
Allow images to oerwrite the windows boarder.
The image number relates to images you have created but not used in your GUI.
For example...
You create an image 'bitmap fn="cat.gif"' it is image 0.
You create another image 'bitmap fn="dog.gif"' it is image 1.
You create another image 'bitmap fn="bird.gif"' it is image 2.
You create a BUTTON using the last image created 'button useimage', the
button used the bird image so it is no longer in the image list.
You create another image 'bitmap fn="frog.gif"' it is image 2.
You now have 3 images available to draw
0 cat
1 dog
2 frog
Drawing images DOES NOT remove images from the image list. Incorporating
images directly in your GUI DOES remove images from the image list. The image
number is NOT related to the buffer number in the bitmap image parameters.
GID 0
-------
GID 0 is used to specify the GUI window itself. It can be used to control certain aspects of the window. (see window docs)
Defining new gadgets during modify
------------------------------------
define
This causes the current line to be used as a Gadget definition statement rather than modify. You can add or replace gadgets in the already opened window. You may need to send a refresh modify command to make the changes visible.
replace="GID"
The newly defined gadget replaces the existing gadget specified by GID. The pipe tries to free the resources used by the previous gadget right away, but some memory is not freed until the pipe is closed.
WHEN USING REPLACE DO NOT ASSUME WHAT THE RESULTING GID OF THE NEW GADGET WILL BE. The usual sequence of allocated gadget ID's is not followed. Replacing a layout group frees all gadgets in the group as well as the layout itself. Replacing a listbrowser frees its nodes.
You MUST keep track and not try to access gadgets that no longer exist.
Generally it is better to close the window and open a new one rather than using replace or define. On the other hand some pretty neat thing can be done using them. ;-D
NOTE: There is a problem when replacing a gadget with a Listbrowser gadget (or a layout containing one). I advise NOT to do this. Open a new window instead.
